-
Notifications
You must be signed in to change notification settings - Fork 62.4k
Polished README for Better First Impressions #39262
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: main
Are you sure you want to change the base?
Conversation
How to review these changes 👓Thank you for your contribution. To review these changes, choose one of the following options: A Hubber will need to deploy your changes internally to review. Table of review linksNote: Please update the URL for your staging server or codespace. This pull request contains code changes, so we will not generate a table of review links. 🤖 This comment is automatically generated. |
Great changes |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Review for GitHub Docs README
This README is very well-structured, engaging, and reader-friendly. It does a great job of guiding new contributors through the project with clear sections and helpful links.
What works well:
The use of emojis and icons (📘, 🛠️, 🌟, ✨, 🧩, 📜, 💬, 💖) adds personality and makes the content visually appealing without overwhelming.
Clear call-to-action sections like “Why Contribute?” and “Ways to Contribute” help motivate and inform potential contributors.
The inclusion of links to relevant resources (contributing guide, issues board, support) ensures readers know exactly where to go next.
The table summarizing the project structure is very helpful for understanding the repo at a glance.
Friendly tone throughout encourages community involvement.
This comment was marked as spam.
This comment was marked as spam.
@NirajDN Man, our README is just a magnet for criticism right now (not unfairly), but it's funny that I just went over this with someone else. The README is actually meant for internal use. Our public docs repo and private docs-internal repo sync several times daily, meaning that any internal-use docs we want hosted on docs-internal are also visible in the public repo. The main problem with the README is that it isn't clear that it's for internal use, which is something I want to correct, but I haven't gotten to it yet. This is our contributing doc for external contributors, but I do currently have someone else tinkering with it in an open PR, so...maybe wait to see what they do with it and what we accept before you pour a lot of time into fixing it up. Edit to add: You might want to read through more of our documentation. We don't really use emoji, and we also have a style guide that might be helpful. |
Hi @Sharra-writes , thanks so much for the context , that really helps clarify things. 🙌 I completely understand now that the current README is intended more for internal use and that the syncing between the public and internal repos makes that a bit tricky to communicate clearly. I’ll hold off on making major changes for now and keep an eye on the open PR you mentioned. Once that settles, I’d love to revisit and contribute in a way that aligns with your internal goals and the established style. Also, I’ll make sure to go through the documentation more thoroughly and familiarize myself with the style guide ,especially around tone and the use of emojis 😅. Thanks again for pointing that out! Let me know if there’s anything small I can help with in the meantime. |
@NirajDN I actually do have an issue that I think would be a great first one for someone. I got the exact wording that needs to be in the relevant article, so it should be a quick fix. If you want something a little more creative, take a look at some of our "about" articles (so any with a title starting with "about"). They've become catch-alls for information that doesn't seem to have another home instead of being what they're supposed to be: a general overview of a subject light on specifics and heavy on "why a reader should care about this product/feature." We're doing a lot of reorganization in Actions, Copilot, and Billing currently, but "about" articles in other categories are fair game if you see one you think you could help cut down. |
Hi @Sharra-writes , thank you so much for sharing this , it sounds like a great opportunity to dive into something meaningful! 🙌 I’d be happy to take on the quick fix you mentioned first ,feel free to drop the link or issue details whenever you get the chance. Also, I really like the idea of revisiting and refining the “about” articles. I’ll start looking through them to spot any that might benefit from being more concise or focused on the “why it matters” angle. Appreciate the trust and guidance ,I’m excited to contribute in a way that aligns with the broader content goals. Let me know where you'd like me to begin!! |
This is the article that needs the update. The section that's inaccurate is "In the blame view, revisions are excluded only if the commit introduced new lines. If the commit was the last to modify a line, it will still appear in blame." It should read
Issue 39078 so you can reference it in your PR, which will close it automatically when the PR is merged. If you need guidance on how to "about" articles should look, About discussions got updated recently. |
github:-NirajDN
Why:
Improving the readability and visual clarity of the main
README.md
file in the GitHub Docs repo. This makes it easier for contributors, especially newcomers, to understand the structure and how to get involved.What's being changed:
README.md
for better clarity and visual structureCheck off the following: